AOI for R

Defining an Area of Interest (AOI)

An area of interest (AOI) is the geographic extent. It helps confine the unit of work to a geographic area, and helps to not only proritize and define research and subsetting efforts, but improves reproducabilty across studies. ‘AOI` is an R package that lets users define an AOI through a common query and return a ’SpatialPolygon’ of that area.

Three parameters can be used to define a query: state, county, and clip_unit. This page illustrates how these parameters can be used define – and refine – a query.

Method 1: Defining an AOI by state

An AOI can be defined by a state name or abbreviation:

CA = getAOI(state = 'CA')

A query can also be defined by multiple states provided as a vector:

WestCoast = getAOI(state = c("Oregon", "Washington", "CA"))

Method 2: Defining an AOI by county

Defining an AOI by county requires a state as well:

EP = getAOI(state = "CO", county = "El Paso")

Multiple counties can be queried if provided as a vector:

centralCoast = getAOI(state ="CA", county = c("Santa Barbara", "San Luis Obispo", "Ventura"))

Method 3: Defining an AOI with a clip_unit

In HydroData a clip_unit is user defined region. Most commonly a bounding box or a supplied shapefile - both of which can be input as a clip_unit.

The clip_unit list()

To define a bounding box clip_unit has four inputs given as a list:

Location
Bounding box height (in miles)
Bounding box width (in miles)
location origin (default = ‘center’)

Again, all clip_unit inputs must be provided as a list. It is also important to note that order DOES matter if each parameter is not explicitly assigned (eg h = 10). Examples for each input follow:

1. Location

A Location is the first input in clip_unit list and can be given as a colloquial name (character string) or as a (lat/long) pair (numeric). Names are geocoded by the Google API via the dismo R package.

Grand Canyon Location example:

Here we query an AOI surrounding the Grand Canyon, using both the colloquial name, and the (lat/long) pair found with a google search. Notice slightly different locations are generated:

GC_name = getAOI(clip_unit = list("grand canyon", 10, 10))

GC_lat_lon = getAOI(clip_unit = list(36.0544, -112.1401, 10, 10))

2. Bounding box height and width

Once a location is specified, the next two needed values are a bounding box height and width (in miles). The first entry defines height and the second width:

National Water Center bounding box diminsions example:

nwc.tall = getAOI(clip_unit = list("National Water Center, AL", 30, 10))
nwc.wide = getAOI(clip_unit = list("National Water Center, AL", 10, 30))

3. Origin

With a location, height, and width defined the relationship of the box to the location is needed. By default (and in the previous examples) each bounding box was generated using the location as a centroid. You can change this by adding a final argument to the clip_unit list specifying where the location lies in reference to the box. Options include ‘center’, ‘lowerleft’, ‘lowerright’, ‘upperleft’, ‘upperright’:

UCSB origin example:

ucsb.c =  getAOI(clip_unit = list("UCSB", 10, 10, "center"))
ucsb.ul = getAOI(clip_unit = list("UCSB", 10, 10, "upperleft"))
ucsb.ur = getAOI(clip_unit = list("UCSB", 10, 10, "upperright"))
ucsb.ll = getAOI(clip_unit = list("UCSB", 10, 10, "lowerleft"))
ucsb.lr = getAOI(clip_unit = list("UCSB", 10, 10, "lowerright"))

Clip_unit by User Shapefile

A user supplied shapefile can be used as input for the clip_unit parameter in lieu of a list() bounding box.

Santa Monica (user shapefile example):

#Read in shapefile of all Los Angeles Communities
LA = rgdal::readOGR("shp/LA.shp", verbose = FALSE)
#Subset Santa Monica
SM = LA[LA$LABEL_CITY == 'Santa Monica',] %>% spTransform(aoiProj)
#Define AOI
AOI = getAOI(clip_unit = SM)

Use Cases

Now that you know how to define an AOI, check out some packages and/or that are using, or could use AOI:

HydroData
nwm
FlowlineFinder
FedData
nhdplusTools